home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_200 / 283_01 / fafnir.doc < prev    next >
Text File  |  1988-12-15  |  24KB  |  492 lines
  1. /* fafnir.doc -- a general purpose forms engine
  2.                  documentation, history
  3.                  9/10/88, david c. oshel
  4.  
  5.     "Why, Doc?"  The user gets Elysian Fields.  The programmer gets 
  6.                  Forms Nirvana.  Fafnir got the Rheingold (*belch*).  
  7.                  That's why.  Anyone for elevenis? -- Oshel, 9/11/88
  8.                  */
  9.  
  10. /*
  11. ============================================================================
  12.     Changes, 12/18/88:
  13.  
  14.     Added Small Model support (SVIDEO.ASM).  Now supports /AL and /AS.
  15.  
  16.     The Fafnir small model is not especially useful in real life, since
  17.     most C programs which manage "live" databases are written, for practical
  18.     reasons, in large model.  However, the small model console i/o library,
  19.     formerly distributed as CIAO.LIB, is included, and that IS useful!
  20.  
  21.  
  22.  
  23.  
  24.     Changes, 12/11/88:
  25.  
  26.     Eliminated snow from CGA direct screen writes.
  27.  
  28.     Microsoft Systems Journal, November 1988, article by Jeff Prosise,
  29.     detailed an "approved" algorithm for CGA snow elimination, so I did
  30.     a complete rewrite on low-level screen i/o in LIAO.LIB to include it.
  31.     Prosise's method tends toward OS/2 treatment of the screen as a general
  32.     data object (a "handle"), instead of a physical component of specific
  33.     hardware.  Accordingly, I isolated all screen writes/reads in functions
  34.     with an MSJ_ prefix; these are the primitives, and contain NO ptrseg
  35.     macros at all, and NO int86's except for:  ROM-BIOS cursor size and 
  36.     location, and module initialization.  (Other parts of the library still
  37.     use int86's, e.g., to read the system clock or the keyboard status.)
  38.  
  39.     Also, corrected a few minor bugs here and there, esp. in Fafnir.  Added
  40.     a "hook" so sliding text fields can call their help functions if user
  41.     presses Shift-F1, Alt-F1, or Ctrl-F1.  Regular F1 still toggles the
  42.     shadow cursor in 80 column reversed field at the bottom of the screen.
  43.  
  44.     The screenmessage() function no longer disturbs field attributes in the
  45.     receiving region.  Added an automatic flag to the scroll routines so
  46.     the blank line at top or bottom of a scrolling window uses the original
  47.     video attribute instead of being upset by wputs().
  48.  
  49.     I rewrote two of Prosise's MSJ_ functions, and added four of my own
  50.     because some of my LIAO and FAFNIR routines expect a length byte, and
  51.     because Prosise did not include an assembler version of mass moves to 
  52.     and from the screen.  My code is in LVIDEO.ASM.  With monochrome
  53.     adapter, some of these routines are so fast you get a "wagon wheel"
  54.     effect on fields which are constantly refreshed by repeating keystroke.
  55.     The CGA snow elimination is rather slow, but seems acceptable.
  56.  
  57.     I am now using *** L A R G E   M O D E L *** exclusively, since nearly
  58.     all of my development puts heavy stress on the heap, and I am getting
  59.     tired of constantly tweaking code in Small Model to use far pointers.
  60.  
  61.     Bugs remaining:  I have not generalized the low-level I/O sufficiently
  62.     to correct problems caused when the hardware screen is wider than 80 
  63.     chars or more than 25 lines.  Deficiencies do not affect normal BW80
  64.     or CO80, or MA, text modes.  Should always vid_init(3) or vid_init(2),
  65.     which has no effect on MA, in applications where this might be a
  66.     hassle.  Upward mobility toward OS/2 or the like will probably cure
  67.     the problem automatically, since a general screen handle will include
  68.     all these dimensions and force low-level code to deal with them.
  69.  
  70.  
  71.  
  72.  
  73.     Changes, 9/30/88:
  74.  
  75.     Added bomb0( char *msg,... ) routine which calls user's crash function
  76.     Added set_crash_function( PTR_TO_CRASH_FN call_on_crash )
  77.     Added exit_fafnir()
  78.  
  79.  
  80.     Changes, 9/24/88:
  81.  
  82.     Added support for sliding fields.  This turned out to be easier than
  83.     I thought it would be.  Something about clear heads on Saturday a.m.'s?
  84.     Also added some idiot-proofing in the EditField routines, to prevent
  85.     still more nonsense in some really quirk-and-ditty field validaters.
  86.  
  87.     Changes, 9/10/88:
  88.  
  89.     Added "seek to end of text" to the END key routine.  Added title and
  90.     version number to the general info.  Promised that Shift_F1 would always
  91.     give the current version display.  Selected Fafnir and Ciao source
  92.     code, with a stand-alone make file, suitable for distribution.  Put the
  93.     F2 exit key back in; turns out this is a useful signal in some existing
  94.     programs that used earlier versions of the field editor.
  95.  
  96.     Changes, 9/4/88:
  97.  
  98.     Changed the dialogue boxes for shorter, intuitive messages about what
  99.     is meant.  Short, sweet and Anglo-Saxon.
  100.  
  101.     Changes, 9/3/88:
  102.  
  103.     Major changes to formedit.h header file, includes macros for standard
  104.     field types and other elegances and graces to avoid egregious errors 
  105.     and make the job easier and safer.
  106.  
  107.     Changes, 9/2/88:
  108.  
  109.     Added the OldRecord flag to EditForm, OnePageEdit, TwoPageEdit, and
  110.     included opening dialogue if OldRecord.  These functions now return
  111.     functionally named MANIFEST CONSTANTS, instead of booleans or function
  112.     keys; except that EditForm can still return PgDn, PgUp, and End to
  113.     flag particular exit conditions.  All other exits from these functions
  114.     are via user dialogue boxes.
  115.  
  116.     The new return values are: SAVE_FORM, SKIP_FORM, DELETE_FORM, STOP_SEARCH
  117.     EditForm also may return:  PGDN, PGUP, or END
  118.  
  119.  
  120.     Changes, 9/1/88:
  121.  
  122.     Altered the FORM_RULES typedef so that fptr is a char **; this allows
  123.     dynamic field allocation!  Added two functions to take advantage:
  124.  
  125.             void AllocateFields( FORM_RULES form[], int NumFields );
  126.             void ReleaseFields( FORM_RULES form[], int NumFields );
  127.  
  128.     Note that if fields are already allocated, it is not necessary to
  129.     to call either of these.  Allocating and assigning to a char *
  130.     whose address is referred to in the FORM_RULES structure is a
  131.     somewhat slippery idea, but it allows for multiple occurrences of
  132.     the identical object within FORM_RULES, provided the second char **
  133.     is not within range of AllocateFields ... think about it!  We gain
  134.     a major savings in space by trading off a lesser redundancy (the
  135.     cost of a field pointer plus its alias) for a greater (the cost of
  136.     two full-size field allocations, or the cost of special code to
  137.     make the alias good with an explicit memcpy), in the case of 
  138.     virtual fields.  The cost to the programmer, when writing FORM_RULES,
  139.     is simply to add an extra & to the name of the field's char *, plus
  140.     a little extra care in deciding who gets allocated (!).  [Note to
  141.     Oshel, from Oshel:  This will be clear as mud in about a month.
  142.     Please be advised that I knew what I was doing when I wrote this!]
  143.     
  144.     It's a design element not easy to weigh, but it seems to me a more 
  145.     powerful idea than simply allocating and assigning directly to the
  146.     fptr's lvalue within the array of FORM_RULES structures.  
  147.  
  148.     AllocateFields() ensures that we are working with null-terminated
  149.     ASCII strings guaranteed to be the proper length.  (No more debugging
  150.     len in FORM_RULES!)  This is a major simplification, especially
  151.     when moving data to and fro between forms and databases.  (No other
  152.     part of the formedit module makes this assumption; it always uses
  153.     the field width, internally.)  The R:Base program interface, e.g.,
  154.     works explicitly with null-terminated strings (cf. a_att(), etc.).
  155.     
  156.  
  157.  
  158.  
  159.     Changes, 8/27/88:
  160.  
  161.     Defined VNOP, in formedit.h, as the "null function".  Any field
  162.     initializer, character validater or field validater equal to VNOP
  163.     is equivalent to a call to a No-Operation.  That is, the character
  164.     typed is valid (EditField), the field is valid, or the field is
  165.     considered to be initialized.  If a character validater in FORM_RULES
  166.     is VNOP, however, the field is display-only (EditForm).  Use cgood()
  167.     or the like to "validate any" printable ASCII keyboard character.
  168.  
  169.     Defined DISPLAY, same as